Meehai's blog
The self hosted blog implementation history
2023-12-01

This is a continuation of the original blog post. This blog has gotten through a bunch of transformations. I think I have reached a good enough architecture, that is bost simple and future proof. In the end, it all went back to a plain simple UNIX philosophy approach. I strongly believe that all software that wants to be in any way extensible and maintainable should follow this approach in one way or another.

History of this blog

Version 1. ValMih plugin (cca. 2020)

This is the version you can see in the original blog post. Here's a small picture of how it used to look like:

The initial design had its own in-browser editor. The software was built on top of ValMih CMS as a plugin. ValMih CMS was a PHP-based CMS me and a colleague did around 2013 after a web summer school we did in the summer after the 1st university year. It was a classical WAMP stack, and to be frank, quite nice to code in. It was actually used for about 2 (3?) years on an real estate site. This was my first 'big' project and I think this is where I developed my first love for designing software. It had some (very) bad coding practices as well. The initial version was a very C-like PHP and some functions (getInfo) was a small ORM that did very complex SELECT queries on the DB.

Later on, I learned OOP and I refactored the CMS into an overly complicated class-based CMS. It had a 'core' but also a plugin system as well as a theme system. The 'login' module was a plugin (as not all websites require logins, duh). The theme class could be swapped by the user from his user profile. The DB was very verbose, with many tables. Each plugin could also write to the DB and store various infos. Everything was stored in the DB, from configs, to users & passwords. One table had the list of activate plugins. Plugins could be installed at 'installation' time from a install.php script. Adding new plugins on an existing install was a bit of a pain, but worked.

The blog post was indeed a plugin of valmih cms. A new instance of the CMS was installed with just 2 plugins: the blog and the login.

At some point the CMS started supporting sqlite as well, as I wanted something more portable than MySQL. sqlite is a 1 file DB, which is super convenient to storing it and loading in very easily. So, the blog content got stored in sqlite around 2021.

Version 2. Express-based blog (cca. 2022)

At some point, I learned about Node, Express and all that JS thing. And so, I though, what could I do to learn this stack better than port the blog to Javascript? Well, that's indeed what I did. The code is available here: link.

Briefly, it looked like this:

The initial version had a HTML-ish language. Basically, it was HTML plus some special html tags that I had created like <div class="title"> and such. At some point, I realized that my HTML dialect just wanted to be markdown language.

Thus, for the javascript version, I had this idea: what if I use a javascript online markdown editor. So, I found EasyMDE, which looked like exactly what I needed. The only problem is: this is a frontend library and it didn't seem trivial to use it in the backend (i.e. node) as well. I had just found out the FE vs. BE issue with javascript: LIBRARIES WRITTEN FOR FRONTEND ARE NOT COMPATIBLE WITH BACKEND AND VICE-VERSA. Holy moly. There are various options to make FE libraries work in the BE, but it's a total mess and nothing is standardized. For backend, I used marked which can be installed via npm.

The editor would also have a bunch of hotkeys:

So, basically, the DB would be updated super often. The content was still in sqlite and stored in gitlab as a private (content only) repository. Now, git isn't the best for binary updates, so every edit would update the entire DB.

Going a bit further, I learned about noSQL DBs. I use BigTable at work and I wanted to get into mongodb. I couldn't manage to install it on the raspberry pi however, because it's arm based and it literally was too hard for what I had wanted. So, I found level db which was surprisingly easy to install. I made a python script to read from sqlite and write to level db and then I used the level npm package to interact with it from JS backend. It's a surprisingly robust and simple to use DB. I can totally recommend it for small projects that want to use a noSQL DB.

Now, why did I use a non relational DB? I don't know, I just wanted to learn. But for the purpose of the blog, it seemed like an overkill.

Version 3. Static website generator directly from markdown files (cca. 2023)

The initial vision of the blog was to have a web-based text editor with a split-screen live editing feature. I'd write my dialect of HTML on the left, parse it and update it via JS on the right. Then, I used easyMDE which did the conversion in real time from markdown to HTML

But then, I realized that the idea of having a web-based text editor is a bit pointless. Github and Gitlab can render markdown. VSCode can render markdown. So, why do I need a web-based blog post editor? I can just use VSCode to write the content and then have a library to the conversion to HTML. I can then use all these static HTML files to create an index page.

So, having this idea in mind, I came up with this simple standalone scripts following UNIX philosophy (1 input, 1 output):

For both these scripts (content and index) I used one common theme which I can edit offline using simple html and css tools.

There were some little things I needed to embed inside the markdown file (like the title, date of posting and other metadata, like tags). In order to do this, I just have a small header at the beggining:

---
title: my title
date: 2023-01-01
tags: [some tag, some other tag]
---

The static website generator code is written in python and can be found here.

I think this is the best design so far. The DB is just a collection of markdown files, which can be diff-ed very easily, so it's simple to just store them in git. The markdown editor is VSCode. The theme can be edited separately w/o the content. The website has no javascript (except the LaTeX parts), so it loads super fast and works offline.

Now it's time to start writing some content 🙃.